EE 
2.18 ERR AND ERL 


VARIABLES 


2.19 ERROR 


When an error handling subroutine is entered, the variable ERR 
contains the error code for the error, and the variable ERL contains 
the number of the line in which the error was detected. The ERR and 
ERL variables are usually used in IF... THEN statements to direct 
program flow in the error trap routine. 


lf the statement that caused the error was a direct mode statement, 
ERL will contain 65535. To test if an error occurred in a direct 
statement, use IF 65535 = ERL THEN ... Otherwise, use: 


IF ERR = error code THEN ... 
IF ERL = line number THEN ... 


If the line number is not on the right side of the relational operator, it 
cannot be renumbered by RENUM. Because ERL and ERR are 
reserved variables, neither may appear to the left of the equal sign in 
a LET (assignment) statement. The MS-BASIC error codes are listed 
in Appendix A. 


FORMAT: 
ERROR <iInteger expression> 
PURPOSE: 


Simulates the occurrence of a MS-BASIC error; or allows error codes 
to be defined by the user. 


REMARKS: 


The value of <integer expression> must be greater than O and less 
than 255. If the value of <integer expression> equals an error code 
already in use by MS-BASIC (see Appendix G), the ERROR statement 
will simulate the occurrence of that error, and the corresponding error 
message will be printed. (See first example.) 


To define your own error code, use a value that is greater than any 
used by the MS-BASIC error codes. (It is preferable to use the highest 
available values, so compatibility may be maintained when more error 
codes are added to MS-BASIC.) This user-defined error code may 
then be conveniently handled in an error trap routine. (See second 
example.) 


If an ERROR statement specifies a code for which no error message 
has been defined, MS-BASIC responds with the message “Unprintable 
Error.” Execution of an ERROR statement for which there is no error 

trap routine causes an error message to be printed and execution 

to halt. 


EXAMPLES: 
LIST 
108 = 10 
20 T=5 


5O ERRORS + T 
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2.20 FIELD 
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40 END 

Ok 

RUN 

String too long in 30 


Or, in direct mode: 


Ok 

ERROR 15 (you type this line) 
String too long (MS-BASIC types this line) 
Ok 


FORMAT: 

FIELD[#]<file number>,<fleld width> AS <string varlable>... 
PURPOSE: 

Allocates space for variables in a random file buffer. 

REMARKS: 


A FIELD statement must be executed to get data out of a random 
buffer after a GET or to enter data before a PUT. 


<file number> is the number under which the file was OPENed. 
<field width> is the number of characters to be allocated to <string 
variable>. For example: 


FIELD 1, 20 AS N$, 10 AS ID$, 40 AS ADD$ 


allocates the first 20 positions (bytes) in the random file buffer to the 
string variable N$, the next 10 positions to ID$, and the next 40 
positions to ADD$. FIELD does NOT place any data in the random 
file buffer. (See LSET/RSET and GET.) 


The total number of bytes allocated in a FIELD statement must not 
exceed the record length that was specified when the file was 
OPENed. Otherwise, a "Field overflow" error occurs. (The default 
record length is 128.) 


Any number of FIELD statements may be executed for the same file, 
and all FIELD statements that have been executed are in effect at the 
same time. 


EXAMPLE: 
see Appendix B. 


NOTE: Do not use a FIELDed variable name in an INPUT or LET 
Statement once a variable name is in random file buffer. If a 
subsequent INPUT or LET statement with that variable name is 
executed, the variable’s pointer is moved to string space. 


a 
2.21 FOR ... NEXT 


FORMAT: 


FOR <varlable>=x TO y [STEP z] 


NEXT [<variable>][,<varlable> ... ] 
where x, y and z are numeric expressions. 
PURPOSE: 


Allows a series of instructions to be performed in a loop a given 
number of times. 


REMARKS: 


<variable> is used as a counter. The first numeric expression (x) is 
the initial value of the counter. The second numeric expression (y) is 
the final value of the counter. The program lines following the FOR 
statement are executed until the NEXT statement is encountered. 
Then the counter is incremented by the amount specified by STEP. A 
check is performed to see if the value of the counter is now greater 
than the final value (y). If it is not greater, MS-BASIC branches back 
to the statement after the FOR statement and the process is 
repeated. If it is greater, execution continues with the statement 
following the NEXT statement. This is a FOR...NEXT loop. If STEP is 
not specified, the increment is assumed to be one. If STEP is 
negative, the final value of the counter is set to be less than the initial 
value. The counter is decremented each time through the loop, and 
the loop is executed until the counter is less than the final value. 


The body of the loop is skipped if the initial value of the loop times 
the sign of the step exceeds the final value times the sign of the step. 


NESTED LOOPS 


A FOR ... NEXT loop may be placed within the context of another 
FOR ... NEXT loop. When loops are nested, each loop must have a 
unique variable name as its counter. The NEXT statement for the 
inside loop must appear before that for the outside loop. If nested 
loops have the same end point, a single NEXT statement may be 
used for all of them. 


The variable(s) in the NEXT statement may be omitted, in which case 
the NEXT statement will match the most recent FOR statement. If a 
NEXT statement is encountered before its corresponding FOR 
statement, a “NEXT without FOR" error message is issued and 
execution is terminated. 


EXAMPLES: 


10 K=10 

RO FOR I=1 TO K STEP 2 
30 PRINT I; 

40 K=K+10 
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2.22 GET 
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50 PRINT K 
60 NEXT I 
RUN 

l 20 

35 30 

5 40 

7 50 

9 60 
Ok 


10 J=0 

20 FOR I=1 TO J 
5O PRINT I 

40 NEXT I 


In this example, the loop does not execute because the initial value 
of the loop exceeds the final value. 


10 I=5 

20 For I=1 TO I+5 

50 PRINT I; 

40 NEXT 

RUN 

l1e264 5 6 7 8 9 10 
Ok 


In this example, the loop executes ten times. The final value for the 
loop variable is always set before the initial value is set. (Note: 
Previous versions of BASIC set the initial value of the loop variable 
before setting the final value; i.e., the above loop would have 
executed six times.) 


FORMAT: 

GET [#]<file number>{,<record number>] 

PURPOSE: 

Reads a record from a random disk file into a random buffer. 
REMARKS: 

<file number> is the number under which the file was OPENed. If 


<record number> is omitted, the next record (after the last GET) is 
read into the buffer. The largest possible record number is 32767. 


EXAMPLE: 
See Appendix B. 


NOTE: After a GET statement, INPUT# and LINE INPUT# may be 
done to read characters from the random file buffer. 


ee 
2.23 GOSUB... 
RETURN 


ES 
2.24 GOTO 


FORMAT: 


GOSUB </ine number> 


RETURN 
PURPOSE: 
Branches to and returns from a subroutine. 
REMARKS: 


<line number> is the first line of the subroutine. A subroutine may be 
called any number of times in a program, and a subroutine may be 
called from within another subroutine. Such nesting of subroutines is 
limited only by available memory. 


The RETURN statement(s) in a subroutine causes MS-BASIC to 
branch back to the statement following the most recent GOSUB 
statement. A subroutine may contain more than one RETURN 
statement, if logic dictate a return at different points in the subroutine. 
Subroutines may appear anywhere in the program, but it is 
recommended that the subroutine be easily distinguishable from the 
main program. Putting a STOP, END or GOTO statement before a 
subroutine will direct program control around it, and prevents 
inadvertent entry into the subroutine. 


EXAMPLE: 


10 GOSUB 40 

20 PRINT “BACK FROM SUBROUTINE” 
oO END 

40 PRINT “SUBROUTINE”; 
50 PRINT “ IN”; 

60 PRINT “ PROGRESS” 

70 RETURN 

RUN 

SUBROUTINE IN PROGRESS 
BACK FROM SUBROUTINE 
Ok 


FORMAT: 
GOTO <line number> 
PURPOSE: 


Branches unconditionally out of the normal program sequence to a 
specified line number. 


REMARKS: 


If </ine number> is an executable statement, that statement and 
those following are executed. If it is a nonexecutable statement, 
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hoe ne Oe R i A A] 
2.25 IF... THENT... 
ELSE] AND IF... 
GOTO 
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execution proceeds at the first executable statement encountered 
after <line number>. 


EXAMPLE: 


LIST 

10 READ R 

20 PRINT “R =”;R, 
560 A=3.14*R’2 
40 PRINT “AREA =”;A 
50 GOTO 10 

60 DATA 5,7,12 

Ok 

RUN 

R=5 

R=7 

R= 12 

?Out of DATA in 10 
Ok 


AREA = 78.5 
AREA = 158.86 
AREA = 452.16 


FORMATS: 

IF <expression> THEN <statement(s)>! <line number> 
[ELSE <statement(s)>| <line number>] 

IF <expression> GOTO <line number> 

[ELSE <statement(s)>! <line number>] 


PURPOSE: 


Makes a decision regarding program flow based on the result 
returned by an expression. 


REMARKS: 


If the result of <expression> is not zero, the THEN or GOTO clause 
is executed. THEN may be followed by either a line number for 
branching or one or more statements to be executed. GOTO is 
always followed by a line number. If the result of <expression> is 
zero, the THEN or GOTO clause is ignored and the ELSE clause, if 
present, is executed. Execution continues with the next executable 
Statement. A comma is allowed before THEN. 


NESTING OF IF STATEMENTS 


IF... THEN ... ELSE statements may be nested. Nesting is limited 
only by the length of the line. 


EXAMPLES: 


IF X>Y THEN PRINT “GREATER” ELSE IF Y>X 
THEN PRINT “LESS THAN” ELSE PRINT “EQUAL” 


is a legal statement. If the statement does not contain the same 
number of ELSE and THEN clauses, each ELSE is matched with the 
closest unmatched THEN. 


ies) 
2.26 INPUT 


IF A=B THEN IF B=C THEN PRINT “A=C” 
ELSE PRINT “A<>C” 


will not print “A<>>C" when A<>B. 
If an IF... THEN statement is followed by a line number in the direct 
mode, an “Undefined line" error results unless a statement with the 
same line number had previously been entered in the indirect mode. 
NOTE: When using IF to test equality for a value that is the result of 
a floating point computation, remember that the internal representation 
of the value may not be exact. Therefore, the test should be against 
the range over which the accuracy of the value may vary. For 
example, to test a computed variable A against the value 1.0, use: 

IF ABS (A-1.0)<1.0E6 THEN ... 


This test returns true if the value of A is 1.0 with a relative error of 
less than 1.0E-6. 


200 IF I THEN GET#1, I 
This statement GETs record number | if | is not zero. 


100 IF(I<20)*(I>10) THEN DB=1979-1:GOTO 300 
110 PRINT “OUT OF RANGE” 


In this example, a test determines if | is greater than 10 and less than 
20. If | is in this range, DB is calculated and execution branches to 
line 300. If | is not in this range, execution continues with line 1110. 

210 IF IOFLAG THEN PRINT A$ ELSE LPRINT A$ 
This statement causes printed output to go either to the terminal or 
the line printer, depending on the value of a variable (IOFLAG). If 


lIOFLAG is zero, output goes to the line printer, otherwise output goes 
to the terminal. 


FORMAT: 

INPUT[;][<“prompt string’>;]<Iist of varlables> 

PURPOSE: 

Allows input from the terminal during program execution. 

REMARKS: 

When an INPUT statement is encountered, program execution pauses 
and a question mark is printed to indicate the program is waiting for 


data. If <"‘prompt string’> is included, the string is printed before the 
question mark. The required data is then entered at the terminal. 
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2.27 INPUT # 
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A comma may be used instead of a semicolon after the prompt string 
to suppress the question mark. For example, the statement INPUT 
“ENTER BIRTHDATE”,B$ will print the prompt with no question mark. 


lf INPUT is immediately followed by a semicolon, then the carriage 
return typed by the user to input data does not echo a carriage 
return/line feed sequence. 


The data that is entered is assigned to the variable(s) given in 
<variable list>. The number of data items supplied must be the same 
as the number of variables in the list. Data items are separated by 
commas. 


The variable names in the list may be numeric or string variable 
names (including subscripted variables). The type of each data item 
that is input must agree with the type specified by the variable name. 
(Strings input to an INPUT statement need not be surrounded by 
quotation marks.) 


Responding to INPUT with too many or too few items, or with the 
wrong type of value (numeric instead of string, etc.) causes the 
message "?Redo from start” to be printed. No assignment of input 
values is made until an acceptable response is given. 


Examples: 
10 INPUT X 
RO PRINT X “SQUARED IS” X*2 
50 END 
RUN 
?5 (The 5 was typed in by the user 
in response to the question mark.) 
5 SQUARED IS 25 
Ok 
LIST 
10 PI=3.14 
RO INPUT “WHAT IS THE RADIUS”:R 
30 A=PI*R’°2 
40 PRINT “THE AREA OF THE CIRCLE IS”;A 
50 PRINT 
60 GOTO 20 
Ok 
RUN 
WHAT IS THE RADIUS? 7.4 (User types 7.4) 
THE AREA OF THE CIRCLE IS 171.9464 
WHAT IS THE RADIUS? 
etc. 
FORMAT: 


INPUT#<file number>,<varlable list> 


2.28 KILL 


PURPOSE: 


Reads data items from a sequential disk file and assigns them to 
program variables. 


REMARKS: 


<file number> is the number used when the file was OPENed for 
input. <variable list> contains the variable names that will be 
assigned to the items in the file. (The variable type must match the 
type specified by the variable name.) With INPUT#, no question mark 
is printed, as with INPUT. 


The data items in the file should appear just as they would if data 
were being typed in response to an INPUT statement. With numeric 
values, leading spaces, carriage returns and line feeds are ignored. 
The first character encountered that is not a space, carriage return or 
line feed is assumed to be the start of a number. The number 
terminates on a space, carriage return, line feed or comma. 


If MS-BASIC is scanning the sequential data file for a string item, 
leading spaces, carriage returns and line feeds are also ignored. The 
first character encountered that is not a space, carriage return, or line 
feed is assumed to be the start of a string item. If this first character 
iS a quotation mark ("'), the string item will consist of all characters 
read between the first quotation mark and the second. Thus, a quoted 
string may not contain a quotation mark as a character. If the first 
character of the string is not a quotation mark, the string is an 
unquoted string, and will terminate on a comma, carriage or line feed 
(or after 255 characters have been read). If end of file is reached 
when a numeric or string item is being INPUT, the item is terminated. 


EXAMPLE: 


See Appendix B. 


FORMAT: 

KILL <filename> 
PURPOSE: 

Deletes a file from disk. 
REMARKS: 


If a KILL statement is given for a file that is currently OPEN, a “File 
already open” error occurs. 


KILL is used for all types of disk files: program files, random data files 
and sequential data files. 


EXAMPLE: 
200 KILL “DATA 1” 
(See Appendix B) 
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2.29 LET 


2.30 LINE INPUT 
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FORMAT: 

[LET] <varlable> = <expression> 

PURPOSE: 

Assigns the value of an expression to a variable. 
REMARKS: 


Notice the word LET is optional, i.e., the equal sign is sufficient when 
assigning an expression to a variable name. 


EXAMPLE: 
110 LET D=12 
120 LET E=12°2 
130 LET F=12°4 
140 LET SUM=D+E+F 
or 
110 D=12 
120 E=12°2 
130 F=12°4 
140 SUM=D+E+F 
FORMAT: 


LINE INPUT[;][<“prompt string’>;]<string variable> 


PURPOSE: 


Inputs an entire line (up to 254 characters) to a string variable, 
without the use of delimiters. 


REMARKS: 


The prompt string is a string literal that is printed at the terminal 
before input is accepted. A question mark is not printed unless it is 
part of the prompt string. All input from the end of the prompt to the 
Carriage return is assigned to <string variable>. However, if a line 
feed/carriage return sequence (this order only) is encountered, both 
characters are echoed; but the carriage return is ignored, the line 
feed is put into <string variable>, and data input continues. 


If LINE INPUT is immediately followed by a semicolon, then the 
Carriage return typed by the user to end the input line does not echo 
a carriage return/line feed sequence at the terminal. 


ee ee 
2.31 LINE INPUT# 


2.32 LIST 


A LINE INPUT may be by-passed by typing ALT-C. MS-BASIC will 
return to command level and type Ok. Typing CONT resumes 
execution at the LINE INPUT. 


EXAMPLE: 


See Example, Section 2.31, LINE INPUT#. 


FORMAT: 
LINE INPUT#<file number>,<string varlable> 
PURPOSE: 


Reads an entire line (up to 254 characters), without delimiters, from a 
sequential disk data file to a string variable. 


REMARKS: 


<file number> is the number under which the file was OPENed. 
<string variable> is the variable name to which the line will be 
assigned. LINE INPUT# reads all characters in the sequential file up 
to a carriage return. It then skips over the carriage return/line feed 
sequence, and the next LINE INPUT# reads all characters up to the 
next carriage return. (If a line feed/carriage return sequence is 
encountered, it is preserved.) 


LINE INPUT# is especially useful if each line of a data file has been 
broken into fields, or if a MS-BASIC program saved in ASCII mode is 
being read as data by another program. 


EXAMPLE: 


10 OPEN “O”,1,”LIST” 

20 LINE INPUT “CUSTOMER INFORMATION? “;C$ 

30 PRINT #1, C$ 

40 CLOSE 1 

50 OPEN “I”,1, LIST” 

60 LINE INPUT #1, C$ 

70 PRINT C$ 

80 CLOSE 1 

RUN 

CUSTOMER INFORMATION? LINDA JONES &8354,4 
MEMPHIS 

LINDA JONES 2544 MEMPHIS 

Ok 


FORMAT 1: 
LIST [</ine number>] 
FORMAT 2: 


LIST [</ine number>[-[<line number>]]] 
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PURPOSE: 

Lists all or part of the program currently in memory at the terminal. 
REMARKS: 

MS-BASIC always returns to command level after a LIST is executed. Nas 
Format 1: If <line number> is omitted, the program is listed beginning 
at the lowest line number. (Listing is terminated either by the end of 
the program or by typing ALT-C.) If </ine number> is included, only 
the specified line will be listed. 


Format 2: This format allows the following options: 


1. If only the first number is specified, that line and all higher- 
numbered lines are listed. 


2. If only the second number is specified, all lines from the beginning 
of the program through that line are listed. 


3. If both numbers are specified, the entire range is listed. 


EXAMPLE: 
Format 1: 

LIST Lists the program currently in memory. 

LIST 500 Lists line 500. S 
Format 2: 

LIST 150- Lists all lines from 150 to the end. 

LIST -1000 Lists all lines from the lowest number 


through 1000. 


LIST 150-1000 Lists lines 150 through 1000, inclusive. 


Ua Se Roe hee) 
2.33 LLIST FORMAT: 
LLIST [</ine number>[-[<line number<]]] 


PURPOSE: | 
Lists all or part of the program currently in memory at the line printer. 
REMARKS: 


LLIST assumes a 132-character wide printer. 


MS-BASIC always returns to command level after an LLIST is 
executed. The options for LLIST are the same as for LIST, Format 2. 
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2.34 LOAD 


-a 
2.35 LPRINT/LPRINT 


USING 


ea) 
2.36 LSET AND RSET 


EXAMPLE: 


See the examples for LIST, format 2. 


FORMAT: 

LOAD <filename>[,R] 

PURPOSE: 

Loads a file from disk into memory. 

REMARKS: 

<filename> is the name that was used when the file was SAVEd. For 
more information on file names and extensions see Appendix C if you 
are CP/M-86 and Appendix D, if you are using MS-DOS. 

LOAD closes all open files and deletes all variables and program 
lines currently residing in memory before it loads the designated 
program. However, if the “R” option is used with LOAD, the program 
is RUN after it is LOADed, and all open data files are kept open. 
Thus, LOAD with the “R” option may be used to chain several 
programs (or segments of the same program). Information may be 
passed between the programs using their disk data files. 


EXAMPLE: 


LOAD “STRTRK" R 


FORMAT: 
LPRINT [<Jist of expressions>] 


LPRINT USING <string exp>;<list of expressions> 


PURPOSE: 


Prints data at the line printer. 
REMARKS: 


Same as PRINT and PRINT USING, except output goes to the line 
printer. See Section 2.48 and Section 2.49. 


LPRINT assumes a 132-character-wide printer. 


FORMAT 
LSET <string variable> = <string expression> 


RSET <string variable> = <string expression> 
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2.37 MERGE 
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PURPOSE: 


Moves data from memory to a random file buffer (in preparation for a 
PUT statement). 


REMARKS: 


If <string expression> requires fewer bytes than were FIELDed to 
<string variable>, LSET left-justifies the string in the field, and RSET 
right-justifies the string. (Spaces are used to pad the extra positions.) 
If the string is too long for the field, characters are dropped from the 
right. Numeric values must be converted to strings before they are 
LSET or RSET. See the MKI$, MKS$, MKD$ functions, Section 3.26. 


Example: 


150 LSET A$=MKS$( AMT) 
160 LSET D$=DESC($) 


NOTE: LSET or RSET may also be used with a non-fielded string 
variable to left-justify or right-justify a string in a given field. For 
example, the program lines: 


110 A$=SPACE$(20) 
120 RSET A$=N$ 


right-justify the string N$ in a 20-character field. This can be very 
handy for formatting printed output. 


FORMAT: 

MERGE <filename> 

PURPOSE: 

Merges a specified disk file into the program currently in memory. 
REMARKS: 


<filename> is the name used when the file was SAVEd. (Your 
operating system may append a default filename extension if one was 
not supplied in the SAVE command. (See Appendix C if your 
Operating system is CP/M-86, or Appendix D if you're using MS-DOS.) 
The file must have been SAVEd in ASCII format. (If not, a “Bad file 
mode" error occurs.) 


If any lines in the disk file have the same line numbers as lines in the 
program in memory, the lines from the file on disk will replace the 
corresponding lines in memory. (MERGEing may be thought of as 
“inserting” the program lines on disk into the program in memory.) 


MS-BASIC always returns to command level after executing a MERGE 
command. 


EXAMPLE: 
MERGE “NUMBRS” 


———— 
2.38 MID$ 


SSS 
2.39 NAME 


FORMAT: 


MID$(<string exp1>,n[,m])=<string exp2> 


where n and m are integer expressions and <string exp1> and 
<string exp2> are string expressions. 


PURPOSE: 


Replaces a portion of one string with another string. 


REMARKS: 


The characters in <string expi>, beginning at position n, are 
replaced by the characters in <string exp2>. The optional m refers to 
the number of characters from <siring exp2> that will be used in the 
replacement. If m is omitted, all of <string exp2> is used. However, 
the replacement of characters never goes beyond the original length 
of <string exp1> regardless of whether m is omitted or included. 


EXAMPLE: 
10 A$="KANSAS CITY, MO” 


20 MID$(A$,14)="KS” 
30 PRINT A$ 


MID$ is also a function that returns a substring of a given string. See 
Section 3.25. 

FORMAT: 

NAME <old filename> AS <new filename> 

PURPOSE: 

Changes the name of a disk file. 

REMARKS: 

<old filename> must exist and <new filename> must not exist: 
otherwise an error will result. After a NAME command, the file exists 
on the same disk, in the same area of disk space, with the new 


name. 


EXAMPLE: 


Ok 
NAME “ACCTS” AS “LEDGER” 
Ok 


In this example, the file that was formerly named ACCTS will now be 
named LEDGER. 
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2.40 NEW 


2.41 NULL 


2.42 ON ERROR 
GOTO 
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FORMAT: 

NEW 

PURPOSE: 

Deletes the program currently in memory and clears all variables. 
REMARKS: 

NEW is entered at command level to clear memory before entering a 
new program. MS-BASIC always returns to command level after a 
NEW is executed. 

FORMAT: 

NULL <integer expression> 

PURPOSE: 

Sets the number of nulls to be printed at the end of each line. 
REMARKS: 

For 10-character-per-second tape punches, <integer expression> 
should be >=3. When tapes are not being punched, <integer 
expression> should be 0 or 1 for Teletypes and Teletype-compatible 
terminal screens, <integer expression> should be 2 or 3 for 30 cps 


hard copy printers. The default value is 0. 


EXAMPLE: 


100 INPUT X l 
200 IF X<50 GOTO 800 


Two null characters will be printed after each line. 


FORMAT: 
ON ERROR GOTO <line number> 
PURPOSE: 


Enables error trapping and specifies the first line of the error handling 
subroutine. 


REMARKS: 


Once error trapping has been enabled, all errors detected—including 


Se ee eee ee Ee) 
2.43 ON ... GOSUB 


AND ON ... GOTO 


2.44 OPEN 


direct mode errors (e.g., Syntax errors) —will cause a jump to the 
specified error handling subroutine. If </ine number> does not exist, 
an “Undefined line” error results. To disable error trapping, execute an 
ON ERROR GOTO 0. Subsequent errors will print an error message 
and halt execution. An ON ERROR GOTO 0 statement that appears 
in an error trapping subroutine causes MS-BASIC to stop and print the 
error message for the error that caused the trap. It is recommended 
that all error trapping subroutines execute an ON ERROR GOTO 0 if 
an error is encountered for which there is no recovery action. 


NOTE: If an error occurs during execution of an error handling 
subroutine, the MS-BASIC error message is printed and execution 
terminates. Error trapping does not occur within the error handling 
subroutine. 


EXAMPLE: 


10 ON ERROR GOTO 1000 


FORMAT: 


ON <expression> GOTO <list of line numbers> 
ON <expression> GOSUB <list of line numbers> 


PURPOSE: 


Branches to one of several specified line numbers, depending on the 
value returned when an expression is evaluated. 


REMARKS: 


The value of <expression> determines which line number in the list 
will be used for branching. For example, if the value is three, the third 
line number in the list will be the destination of the branch. (If the 
value is a noninteger, the fractional portion is rounded.) In the 
ON...GOSUB statement, each line number in the list must be the first 
line number of a subroutine. If the value of <expression> is zero or 
greater than the number of items in the list (but less than or equal to 
255), MS-BASIC continues with the next executable statement. If the 
value of <expression> is negative or greater than 255, an "Illegal 
function call" error occurs. 


EXAMPLE: 
100 ON L-1 GOTO 150,300,320,590 


FORMAT: 
OPEN <mode>,[#iflle number>,<filename>,[<recien>] 
PURPOSE: 


Allows |/O to a disk file. 
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2.45 OPTION BASE 


2.46 OUT 
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REMARKS: A disk file must be OPENed before any disk I/O operation 
can be performed on that file. OPEN allocates a buffer for I/O to the 
file and determines the access mode to be used with the buffer. 


<mode> is a string expression whose first character is one of the 


following: Me cal 


O specifies sequential output mode 
| specifies sequential input mode 


R specifies random input/output mode 


<file number> is an integer expression whose value is between one 
and fifteen. The number is then associated with the file for as long as 
it is OPEN and is used to refer other disk I/O statements to the file. 


<filename> is a string expression containing a name that conforms to 
your operating system's rules for disk filenames. 


<recien> is an integer expression which, if included, sets the record 
length for random files. The default record length is 128 bytes. 


NOTE: A file can be OPENed for sequential input or random access 
on more than one file number at a time. A file may be OPENed for 
output, however, on only one file number at a time. 
EXAMPLE: 
10 OPEN “I”,2,"INVEN” Vas 


See also Appendix B. 


FORMAT: 
OPTION BASE n 
where nis 1 or 0 
PURPOSE: 
Declares the minimum value for array subscripts. 
REMARKS: 
The default base is 0. If the statement 
OPTION BASE 1 


is executed, the lowest value an array subscript may have is one. 


FORMAT: 
OUT 1,J 


2.47 POKE 


2.48 PRINT 


where | and J are integer expressions in the range 0 to 65535. | is a 
machine port number, and J is the data to be transmitted. 


PURPOSE: 
Sends a byte to a machine output port. 
REMARKS: 


The integer expression | is the port number, and the integer 
expression J is the data to be transmitted. 


EXAMPLE: 
100 OUT 128345,225 
In assembly language, this is equivalent to: 


MOV DX,12345 
MOV AL,255 
OUT DX,AL 


FORMAT: 

POKE I,J 

where | and J are integer expressions 
PURPOSE: 

Writes a byte into a memory location. 
REMARKS: 


The integer expression | is the address of the memory location to be 
POKEd. The integer expression J is the data to be POKEd. J must be 
in the range O to 255. | must be in the range 0 to 65536. 


The complementary function to POKE is PEEK. The argument to 
PEEK is an address from which a byte is to be read. See Section 
3.28. 


POKE and PEEK are useful for efficient data storage, loading 
assembly language subroutines, and passing arguments and results to 
and from assembly language subroutines. 


EXAMPLE: 


10 POKE & H5A00, & HFF 


FORMAT: 
PRINT [<list of expressions>| 
PURPOSE: 


Outputs data at the terminal. 
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50 


REMARKS: 


If <list of expressions> is omitted, a blank line is printed. If </ist of 
expressions> is included, the values of the expressions are printed at 
the terminal. The expressions in the list may be numeric and/or string 
expressions. (Strings must be enclosed in quotation marks.) 


PRINT POSITIONS 


The position of each printed item is determined by the punctuation 
used to separate the items in the list. MS-BASIC divides the line into 
print zones of 14 spaces each. In the list of expressions, a comma 
causes the next value to be printed at the beginning of the next zone. 
A semicolon causes the next value to be printed immediately after the 
last value. Typing one or more spaces between expressions has the 
same effect as typing a semicolon. 


lf a comma or a semicolon terminates the list of expressions, the next 
PRINT statement begins printing on the same line, spacing 
accordingly. If the list of expressions terminates without a comma or 
a semicolon, a carriage return is printed at the end of the line. If the 
printed line is longer than the terminal width, MS-BASIC goes to the 
next physical line and continues printing. 


Printed numbers are always followed by a space. Positive numbers 
are preceded by a space. Negative numbers are preceded by a 
minus sign. Single precision numbers that can be represented with 6 
or fewer digits in the unscaled format no less accurately than they 
can be represented in the scaled format, are output using the 
unscaled format. For example, 1E-7 is output as 0000001 and 1E-8 is 
output as 1E-08. Double precision numbers that can be represented 
with 16 or fewer digits in the unscaled format no less accurately than 
they can be represented in the scaled format, are output using the 
unscaled format. For example, 1D-16 is output as 
-00000000000000001 and 1D-17 is output as 1D-17. A question mark 
may be used in place of the word PRINT in a PRINT statement. 


Examples: 


10 X=5 
20 PRINT X+5, X-5, X*(-5), X°5 
oO END 
RUN 
10 0 -25 5125 
Ok 


In this example, the commas in the PRINT statement cause each 
value to be printed at the beginning of the next print zone. 


LIST 

10 INPUT X 

RO PRINT X “SQUARED IS” X*2 “AND”; 
50 PRINT X “CUBED IS” X^3 

40 PRINT 

50 GOTO 10 

Ok 


2.49 PRINT USING 


RUN 
? 9 
9 SQUARED IS 81 AND 9 CUBED IS 729 


? RL 
21 SQUARED IS 441 AND 21 CUBED IS 9261 


? 


In this example, the semicolon at the end of line 20 causes both 
PRINT statements to be printed on the same line, and line 40 causes 
a blank line to be printed before the next prompt. 


10 FOR X = 1 TO 5 


5 10 10 20 15 30 20 40 285 50 


In this example, the semicolons in the PRINT statement cause each 
value to be printed immediately after the preceding value. (Don't 
forget, a number is always followed by a space and positive numbers 
are preceded by a space.) In line 40, a question mark is used instead 
of the word PRINT. 

FORMAT: 

PRINT USING <string exp>;<list of expressions> 

PURPOSE: 

Prints strings or numbers using a specified format. 

REMARKS AND EXAMPLES: 

<list of expressions> is comprised of the string or numeric 
expressions that are to printed, separated by semicolons. <string 
exp> is a string literal (or variable) comprised of special formatting 


characters. These formatting characters (see below) determine the 
field and the format of the printed strings or numbers. 


STRING FIELDS 


When PRINT USING is used to print strings, one of three formatting 
characters may be used to format the string field: 


! Specifies that only the first character in the given 
string is to be printed. 
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\n spaces\ Specifies that 2+n characters from the string are to 


be printed. If the backslashes are typed with no 
Spaces, two characters will be printed; with one 
space, three characters will be printed, and so on. If 
the string is longer than the field, the extra 
characters are ignored. If the field is longer than the 
String, the string will be left-justified in the field and 
padded with spaces on the right. 


EXAMPLE: 


10 A$="LOOK”:B$="0UT” 

50 PRINT USING “!”:A$;B$ 

40 PRINT USING “\ \”;A$;B$ 

50 PRINT USING “\ \”;A$;B$;"1!” 
RUN 

LO 

LOOKOUT 

LOOK OUT !! 


Specifies a variable length string field. When the field 
is specified with “&'', the string is output exactly as input. 


EXAMPLE: 


10 A$="LOOK”:B$="0UT” 
RO PRINT USING “!”.A$; 
50 PRINT USING “8”; B$ 
RUN 
LOUT 


NUMERIC FIELDS 


When PRINT USING is used to print numbers, the following special 
characters may be used to format the numeric field: 


# 


A number sign is used to represent each digit 
position. Digit positions are always filled. If the 
number to be printed has fewer digits than positions 
specified, the number will be right-justified (preceded 
by spaces) in the field. 


A decimal point may be inserted at any position in 
the field. If the format string specifies that a digit is 
to precede the decimal point, the digit will always be 
printed (as 0 if necessary). Numbers are rounded as 
necessary. 


PRINT USING “## ##”..78 
0.78 


PRINT USING “###_ ##":987 654 
987.65 


PRINT USING “##.## “:10.2,5.3,66.789,.234 
10.20 530 66.79 023 


we 


$$ 


**§$ 


In the last example, three spaces were inserted at 
the end of the format string to separate the printed 
values on the line. 


A plus sign at the beginning or end of the format 
string will cause the sign of the number (plus or 
minus) to be printed before or after the number. 


A minus sign at the end of the format field will cause 
negative numbers to be printed with a trailing 
minus sign. 


PRINT USING “+##,## “:-68.95,2.4,55.6,.9 
68.95 +240 +5560 -0.90 


PRINT USING “##.##- “;-68.95 22.449,-7.01 
68.95- 2245 7.01- 


A double asterisk at the beginning of the format 
string causes leading spaces in the numeric field 
to be filled with asterisks. The ** also specifies 
positions for two more digits. 


PRINT USING “**#.# “;12.39,-0.9,765.1 
"124 *-09 765.1 


A double dollar sign causes a dollar sign to be 
printed to the immediate left of the formatted number. 
The $$ specifies two more digit positions, one of 
which is the dollar sign. The exponential format 
cannot be used with $$. Negative numbers cannot 
be used unless the minus sign trails to the right. 


PRINT USING “$$###,##":456.78 
$456.78 


The **$ at the beginning of a format string combines 
the effects of the above two symbols. Leading 
spaces will be asterisk-filled and a dollar sign will be 
printed before the number. **$ specifies three more 
digit positions, one of which is the dollar sign. 


PRINT USING “**$## ##":2.34 
xk *$2 34 


A comma that is to the left of the decimal point in a 
formatting string causes a comma to be printed to 
the left of every third digit to the left of the decimal 
point. A comma that is at the end of the format 
string is printed as part of the string. A comma 
specifies another digit position. The comma has no 
effect if used with the exponential (—) format. 


PRINT USING “####,##":1234.5 
1,254.50 


PRINT USING “#### ## 1234.5 
1234.50, 
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ARAA 


% 


FORMAT: 


PURPOSE: 


REMARKS: 


Four carets (or up-arrows) may be placed after the 
digit position characters to specify exponential 
format. The four carets allow space for E+xx to be 
printed. Any decimal point position may be specified. 
The significant digits are left-justified, and the 
exponent is adjusted. Unless a leading + or trailing + 
or — is specified, one digit position will be used to 
the left of the decimal point to print a space or a 
minus sign. 


PRINT USING “##,##".°**"°234.56 
2.55E+0R 


PRINT USING “.####°°**-":888888 
8889E+06 


PRINT USING “+.##°°**°":123 
+.12E+03 


An underscore in the format string causes the next 
character to be output as a literal character. 


PRINT USING “— !##.##__ |";12.34 
112.34! 


The literal character itself may be an underscore by 
placing "—" in the format string. 


If the number to be printed is larger than the 
specified numeric field, a percent sign is printed in 
front of the number. If rounding causes the number 
to exceed the field, a percent sign will be printed in 
front of the rounded number. 


PRINT USING “##,##":111.22 
%111.22 


PRINT USING “.##”; 999 
%1.00 


If the number of digits specified exceeds 24, an 
“Illegal function call” error will result. 


PRINT#<fllenumber>,[USING<string exp>;]<list 
of exps> 


Writes data to a sequential disk file. 


<file number> is the number used when the file was OPENed for 


‘aug 


output. <string exp> is comprised of formatting characters as 
described in Section 2.49, PRINT USING. The expressions in </ist of 
expressions> are the numeric and/or string expressions that will be 
written to the file. 

PRINT# does not compress data on the disk. An image of the data is 
written to the disk, just as it would be displayed on the terminal 
screen with a PRINT statement. For this reason, care should be taken 


to delimit the data on the disk, so that it will be input correctly from 
the disk. 


In the list of expressions, numeric expressions should be delimited by 
semicolons. 


EXAMPLE: 
PRINT#¥1,A;B:C;X;Y;Z 


(If commas are used as delimiters, the extra blanks that are inserted 
between print fields will also be written to disk.) 


String expressions must be separated by semicolons in the list. To 
format the string expressions correctly on the disk, use explicit 
delimiters in the list of expressions. 


For example, let A$=""CAMERA” and B$="93604-1". The statement 
PRINT#1,A$;B$ 
would write CAMERA93604-1 to the disk. Because there are no 
delimiters, this could not be input as two separate strings. To correct 
the problem, insert explicit delimiters into the PRINT# statement as 
follows: 
PRINT#1,A$;”,”;B$ 
The image written to disk is: 


CAMERA 93604-1 


which can be read back into two string variables. 


If the strings themselves contain commas, semicolons, significant 
leading blanks, carriage returns, or line feeds, write them to disk 
surrounded by explicit quotation marks, CHR§$(34). 


For example, let A$="CAMERA, AUTOMATIC" and B$=" 93604-1”. 
The statement 


PRINT#1,A$;B$ 
would write the following image to disk: 


CAMERA, AUTOMATIC 93604-1 
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and the statement 
INPUT#1,A$,B$ 
would input "CAMERA" to A$ and “AUTOMATIC 93604-1" to B$. To 


separate these strings properly on the disk, write double quotes to the 
disk image using CHR$(34). The statement 


PRINT#1 CHR$(34);A$;CHR$( 34 );CHRS(34);B$;CHRS( 34) 
writes the following image to disk: 


“CAMERA, AUTOMATIC”” 93604-1" 


and the statement 


INPUT#1,A$,B$ 
would input “CAMERA, AUTOMATIC” to A$ and "93604-1" to B$. 


The PRINT# statement may also be used with the USING option to 
control the format of the disk file. 


EXAMPLE: 
PRINT#1 USING”$$###.##”;J;K;L 


See Appendix B. See also WRITE#, Section 2.67. 


FORMAT: 
PUT [#]<flle number>[{,<record number>] 


PURPOSE: 

Writes a record from a random buffer to a random disk file. 
REMARKS: 

<file number> is the number under which the file was OPENed. If 
<record number> is omitted, the record will have the next available 
record number (after the last PUT). The largest possible record 
number is 32767. The smallest record number is 1. 

EXAMPLE: 


See Appendix B. 


NOTE: PRINT#, PRINT# USING, and WRITE# may be used to put 
characters in the random file buffer before a PUT statement. 


With WRITE#, MS-BASIC pads the buffer with spaces up to the 
Carriage return. Any to read or write past the end of the buffer causes 
a “Field overflow” error. 


2.52 RANDOMIZE 


2.53 READ 


FORMAT: 


RANDOMIZE [<expression>] 


PURPOSE: 
Reseeds the random number generator. 
REMARKS: 


lf <expression> is omitted, MS-BASIC suspends program execution 
and asks for a value by printing: 


Random Number Seed (-32768 to 32767)? 


before executing RANDOMIZE. 


If the random number generator is not reseeded, the RND function 
returns the same sequence of random numbers each time the 
program is RUN. To change the sequence of random numbers every 
time the program is RUN, place a RANDOMIZE statement at the 
beginning of the program and change the argument with each RUN. 


EXAMPLE: 


10 RANDOMIZE 
20 FOR I=1 TO 5 


Random Number Seed (-32768 to 32767)? 3 (user 
types 3) 
88598 484668 586328 .119426 .709225 
Ok 
RUN 
Random Number Seed (-32768 to 32767)? 4 (user 
types 4 for new sequence) 
803506 .162462 929364 2924435 322921 
Ok 
RUN 
Random Number Seed (-32768 to 32767)? 3 (same 
sequence as first RUN) 
88598 484668 586328 .119426 .709225 
Ok 


FORMAT: 
READ <list of varilables> 
PURPOSE: 


Reads values from a DATA statement and assigns them to variables. 
(See DATA, Section 2.9.) 
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REMARKS: 


A READ statement must always be used in conjunction with a DATA 
Statement. READ statements assign variables to DATA statement 
values on a one-to-one basis. READ statement variables may be 
numeric or string, and the values read must agree with the variable 
types specified. If they do not agree, a “Syntax error” will result. 


A single READ statement may access one or more DATA statements 
(they will be accessed in order), or several READ statements may 
access the same DATA statement. If the number of variables in <list 
of variables> exceeds the number of elements in the DATA 
Statement(s), an OUT OF DATA message is printed. If the number of 
variables specified is fewer than the number of elements in the DATA 
Statement(s), subsequent READ statements will begin reading data at 
the first unread element. If there are no subsequent READ statements, 
the extra data is ignored. 


To reread DATA statements from the start, use the RESTORE 
Statement (see RESTORE, Section 2.56). 


EXAMPLE: 


80 FOR I=1 TO 10 

90 READ A(T) 

100 NEXT I 

110 DATA 3.08,5.19,3.12,3.98,4.24 
120 DATA 5.08,5.55,4.00,3.16,3.37 


This program segment READs the values from the DATA statements 
into the array A. After execution, the value of A(1) will be 3.08, and so 
on. 


EXAMPLE: 


LIST 

10 PRINT “CITY”, “STATE”, “ ZIP” 

20 READ C$S$Z 

50 DATA “DENVER,”, COLORADO, 80211 
40 PRINT C$,S$Z 


Ok 

RUN 

CITY STATE ZIP 
DENVER, COLORADO 80211 
Ok 


This program READs string and numeric data from the DATA 
statement in line 30. 


FORMAT: 


REM <remark> 


2.55 RENUM 


PURPOSE: 
Allows explanatory remarks to be inserted in a program. 
REMARKS: 


REM statements are not executed but are output exactly as entered 
when the program is listed. 


REM statements may be branched into from a GOTO or GOSUB 
statement. Execution will continue the first executable statement after 
the REM statement. 


Remarks may be added to the end of a line by preceding the remark 
with a single quotation mark instead of :REM. 


WARNING: Do not use this in a data statement as it would be 
considered legal data. 


EXAMPLE: 


120 REM CALCULATE AVERAGE VELOCITY 
130 FOR I=1 TO 20 
140 SUM=SUM + V(I) 


Or: 


120 FOR I=1 TO 20 ‘CALCULATE AVERAGE 
VELOCITY 

130 SUM=SUM+V(T) 

140 NEXT I 


FORMAT: 

RENUM [[<new number>][,[<old number>]{,</ncrement>]]] 
PURPOSE: 

Renumbers program lines. 

REMARKS: 

<new number> is the first line number to be used in the new 
sequence. The default is 10. <o/d number> is the line in the current 
program where renumbering is to begin. The default is the first line of 


the program. <increment> is the increment to be used in the new 
sequence. The default is 10. 
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RENUM also changes all line number references following GOTO, 
GOSUB, THEN, ON...GOTO, ON...GOSUB and ERL statements to 
reflect the new line numbers. If a nonexistent line number appears 
after one of these statements, the error message “Undefined line 
XXXXXx in yyyyy” is printed. The incorrect line number reference 
(xxxxx) is not changed by RENUM, but line number yyyyy may be 
changed. 


NOTE: RENUM cannot be used to change the order of program lines 
(for example, RENUM 15,30 when the program has three lines 
numbered 10, 20 and 30) or to create line numbers greater than 
65529. An “Illegal function call” error will result. 


Examples: 


RENUM Renumbers the entire program. 
The first new line number will 
be 10. Lines will increment by 
10. 


RENUM 300,,50 Renumbers the entire program. 
The first new line number will 
be 300. Lines will increment by 
50. 


RENUM 1000,900,20 Renumbers the lines from 900 
up so they start with line 
number 1000 and increment 
by 20. 


FORMAT: 

RESTORE [<l/ine number>] 

PURPOSE: 

Allows DATA statements to be reread from a specified line. 
REMARKS: 


After a RESTORE statement is executed, the next READ statement 
accesses the first item in the program's first DATA statement. If </ine 
number> is specified, the next READ statement accesses the first 
item in the specified DATA statement. 


EXAMPLE: 


10 READ ABC 

20 RESTORE 

50 READ DEF 

40 DATA 57, 68, 79 


2.57 RESUME 


2.58 RUN 


FORMATS: 

RESUME 

RESUME 0 

RESUME NEXT 
RESUME <line number> 
PURPOSE: 


Continues program execution after an error recovery procedure has 
been performed. 


REMARKS: 


Any one of the four formats shown above may be used, depending 
upon where execution is to resume: 


RESUME Execution resumes at the 

or statement which caused the 

RESUME 0 error. 

RESUME NEXT Execution resumes at the statement 
immediately following the one which caused 
the error. 


RESUME <line number> Execution resumes at </ine number>. 


A RESUME statement that is not in an error trap routine causes a 
“RESUME without error" message to be printed. 


EXAMPLE: 
10 ON ERROR GOTO 900 


900 IF (ERR=230)AND(ERL=90) THEN PRINT “TRY 


AGAIN”: RESUME 80 


FORMAT 1: 

RUN [</ine number>] 

PURPOSE: 

Executes the program currently in memory. 


REMARKS: 


If <line number> is specified, execution begins on that line. 
Otherwise, execution begins at the lowest line number. MS-BASIC 
always returns to command level after a RUN is executed. 
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EXAMPLE: 

RUN 
FORMAT 2: 
RUN <filename>{[,R] 
PURPOSE: 


Loads a file from disk into memory and runs it. 


REMARKS: 


<filename> is the name used when the file was SAVEd. See 
Appendix C for CP/M-86 and Appendix D for MS-DOS. 


RUN closes all open files and deletes the current contents of memory 
before loading the designated program. However, with the “R” option, 
all data files remain OPEN. 


EXAMPLE: 
RUN “NEWFIL” R 
See Appendix B. 


NOTE: The MS-BASIC Compiler supports the RUN and RUN <line 
number> forms of the RUN statement. The MS-BASIC Compiler does 
not support the “R” option with RUN. If you want this feature, the 
CHAIN statement should be used. 


FORMAT: 

SAVE <filename>[,A | ,P] 
PURPOSE: 

Saves a program file on disk. 
REMARKS: 


<filename> is a quoted string that conforms to your operating 
system's requirements for filenames. Your operating system may 
append a default filename extension if one was not supplied in the 
SAVE command. See Appendix C if you are using CP/M-86, or 
Appendix D if your operating system is MS-DOS. If <filename> 
already exists, the file will be written over. 


Use the A option to save the file in ASCII format. Otherwise, MS-BASIC 
Saves the file in a compressed binary format. ASCII format takes 

more space on tne disk, but some disk access requires that files be 

in ASCII format. For instance, the MERGE command requires and 
ASCII format file, and some operating system commands such as 
LIST may require an ASCII format file. 


2.60 STOP 


2.61 SWAP 


Use the P option to protect the file by saving it in an encoded binary 
format. When a protected file is later RUN (or LOADed), any attempt 
to list or edit it will fail. 


Examples: 
 SAVE"COM2”,A 
SAVE”PROG”,P 


See also Appendix B, “MS-BASIC Disk 1/0." 


FORMAT: 

STOP 

PURPOSE: 

Terminates program execution and returns to command level. 
REMARKS: 


STOP statements may be used anywhere in a program to 
terminate execution. When a STOP is encountered, the following 
message is printed: 


Break in line nnnnn 


Unlike the END statement, the STOP statement does not close files. 


MS-BASIC always returns to command level after a STOP is executed. 
Execution is resumed by issuing a CONT command (see Section 2.7). 


EXAMPLE: 


10 INPUT A,B,C 
20 K=A°2*5.3:L=B’°3/.26 
50 STOP 
40 M=C*K+100:PRINT M 
RUN 
212,05 
BREAK IN 50 
Ok 
PRINT L 
50.7692 
Ok 
CONT 
115.9 
Ok 


FORMAT: 


SWAP <varilable>,<varlable> 
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2.62 TRON/TROFF 
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PURPOSE: 

Exchanges the values of two variables. 

REMARKS: 

Any type variable may be SWAPped (integer, single precision, double 


precision, string), but the two variables must be of the same type or a 
“Type mismatch" error results. 


EXAMPLE: 
LIST 
10 A$=“ ONE ” : B$=" ALL ” : C$=“FOR” 
RO PRINT A$ C$ B$ 
50 SWAP A$, B$ 
40 PRINT A$ C$ B$ 
RUN 
Ok 
ONE FOR ALL 
ALL FOR ONE 
Ok 
FORMAT: 
TRON 
TROFF 
PURPOSE: 


Traces the execution of program statements. 
REMARKS: 


As an aid in debugging, the TRON statement (executed in either the 
direct or indirect mode) enables a trace flag that prints each line 
number of the program as it is executed. The numbers appear 
enclosed in square brackets. The trace flag is disabled with the 
TROFF statement (or when a NEW command is executed). 


EXAMPLE: 


TRON 

Ok 

LIST 

10 K=10 

RO FOR J=1 TO 2 
50 L=K + 10 
40 PRINT J;K;L 
50 K=K+10 

60 NEXT 

70 END 

Ok 

RUN 


2.63 WAIT 


2.64 WHILE... 
WEND 


[10][20][30][40] 1 10 20 
[50][60][30][40] 2 20 30 
[50][60][70] 

Ok 

TROFF 

Ok 


FORMAT: 


WAIT <port number>, \[,J] 


where | and J are integer expressions 
PURPOSE: 


Suspends program execution while monitoring the status of a 
machine input port. 


REMARKS: 

The WAIT statement causes execution to be suspended until a 
specified machine input port develops a specified bit pattern. The 
data read at the port is exclusive ORed with the integer expression J, 
and then ANDed with |. If the result is zero, MS-BASIC loops back and 
reads the data at the port again. If the result is nonzero, execution 
continues with the next statement. If J is omitted, it is assumed to be 
zero. 

CAUTION: It is possible to enter an infinite loop with the WAIT 


statement, in which case it will be necessary to manually restart the 
machine. 


EXAMPLE: 


100 WAIT 38,4 


FORMAT: 


WHILE <expression> 
[<loop statements>] 
WEND 

PURPOSE: 


Executes a series of statements in a loop as long as a given 
condition is true. 
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REMARKS: 


If <expression> is not zero (i.e., true), </oop statements> are 

executed until the WEND statement is encountered. MS-BASIC then 

returns to the WHILE statement and checks <expression>. If it is still Co 
true, the process is repeated. If it is not true, execution resumes with 

the statement following the WEND statement. 


WHILE/WEND loops may be nested to any level. Each WEND will 
match the most recent WHILE. An unmatched WHILE statement 
causes a “WHILE without WEND" error, and an unmatched WEND 
statement causes a "WEND without WHILE” error. 


EXAMPLE: 


90 ‘BUBBLE SORT ARRAY A$ 

100 FLIPS=1 ‘FORCE ONE PASS THRU LOOP 

110 WHILE FLIPS 

115 FLIPS=0 

120 FOR I=1 TO J-l 

130 IF A$(I)>A$(I+1) THEN 
SWAP A&(I), 
A$(I+1):FLIPS=1 

140 NEXT I 

150 WEND 


FORMAT: 
WIDTH [LPRINT] </nteger expression> 
PURPOSE: 


Sets the printed line width (in number of characters) for the terminal 
or line printer. 


REMARKS: 


If the LPRINT option is omitted, the line width is set at the terminal. If 
LPRINT is included, the line. width is set at the line printer. <integer 
expression> must have a value in the range 15 to 255. The default 
width is 72 characters. 


If <integer expression> is 255, the line width is "infinite;” that is, 
MS-BASIC never inserts a carriage return. However, the position of the 
cursor or the print head, as given by the POS or LPOS function, 
returns to zero after position 255. 


EXAMPLE: 
10 PRINT “ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
RUN 
ABCDEFGHIJKLMNOPQRSTUVWXYZ ee 
Ok 


WIDTH 18 
Ok 


2.66 WRITE 


2.67 WRITE# 


ay 


RUN 
ABCDEFGHIJKLMNOPQR 
STUVWXYZ 

Ok 


FORMAT: 


WRITE[</ist of expressions>] 
PURPOSE: 


Outputs data at the terminal. 
REMARKS: 


If <Jist of expressions> is omitted, a blank line is output. If </st of 
expressions> is included, the values of the expressions are output at 
the terminal. The expressions in list may be numeric and/or string 
expressions, and they must be separated by commas. 


When the printed items are output, each item will be separated from 
the last by a comma. Printed strings will be delimited by quotation 
marks. After the last item in the list is printed, MS-BASIC inserts a 
carriage return/line feed. 


WRITE outputs numeric values using the same format as the PRINT 
statement, Section 2.48. 


EXAMPLE: 
10 A=80:B=90:C$="“THAT’S ALL” 
20 WRITE A,B,C$ 
RUN 
80, 90,“THAT’S ALL” 
Ok 
FORMAT: 


WRITE#<file number>,<list of expressions> 
PURPOSE: 

Writes data to a sequential file. 

REMARKS: 


<file number > is the number under which the file was OPENed in 
“O” mode. The expressions in the list are string or numeric 
expressions. and they must be separated by commas. 


The difference between WRITE# and PRINT# is that WRITE# inserts 
commas between the the items as they are written to disk and 
delimits strings with quotation marks. Therefore, it is not necessary for 
the user to put explicit delimiters in the list. A carriage return/line 
feed sequence is inserted after the last item in the list is written to 
disk. 
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EXAMPLE: 

Let A$="CAMERA” and B$="93604-1". The statement: 
WRITE#1,A$,B$ 

writes the following image to disk: 
“CAMERA","93604-1” 

A subsequent INPUT# statement, such as: 
INPUT#1,A$,B$ 

would input “CAMERA” to A$ and "93604-1” to B$. 


3.1 ABS 


3.2 ASC 


3. MS-BASIC FUNCTIONS 


This chapter discusses the intrinsic functions provided by MS-BASIC 
are presented in this chapter. The functions may be called from any 


program without further definition. 


Arguments to functions are always enclosed in parentheses. In the 
formats given for the functions in this chapter, the arguments have 
been abbreviated as follows: 


X and Y Represent any numeric expressions 
| and J Represent integer expressions 
X$ and Y$ Represent string expressions 


lf a floating point value is supplied where an integer is required, 
MS-BASIC will round the fractional portion and use the resulting 
integer. 

NOTE: With the MS-BASIC interpreter, only integer and single 
precision results are returned by the functions described in this 
chapter. Double precision functions are supported only by the 
MS-BASIC Compiler. 

FORMAT: 

ABS(X) 

ACTION: 


Returns the absolute value of the expression X. 


EXAMPLE: 
PRINT ABS(7*(-5)) 
35 
Ok 
FORMAT: 
ASC(X$) 
ACTION: 


Returns a numerical value that is the ASCII code of the first character 
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3.3 ATN 


3.4 CDBL 


3.5 CHR$ 
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of the string X$. (See Appendix D for ASCII codes.) If X$ is null, an 
“Illegal function call” error is returned. 


EXAMPLE: 
10 X$ = “TEST” 
20 PRINT ASC(X$) 
RUN 
84 
Ok ) 


See the CHR$ function for ASCII-to-string conversion. 


FORMAT: 

ATN(X) 

ACTION: 

Returns the arctangent of X in radians. Result is in the range -pi/2 to 


pi/2. The expression X may be any numeric type, but the evaluation 
of ATN is always performed in single precision. 


EXAMPLE: 
10 INPUT X 
20 PRINT ATN(X) 
RUN 
? 83 
1.249046 
Ok 
FORMAT: 
CDBL(X) 
ACTION: 


Converts X to a double precision number. 


EXAMPLE: 

10 A = 454.67 

20 PRINT A:CDBL(A) 

RUN 

454.67 454.6699829101563 

Ok 
FORMAT: = 
CHRS(I) 


3.6 CINT 


3.7 COS 


ACTION: 
Returns a string whose one element has ASCII code |. (ASCII codes 
are listed in Appendix D.) CHR$ is commonly used to send a special 
character to the terminal. For instance, the BEL character could be 
sent (CHR$(7)) as a preface to an error message, or a form feed 
could be sent (CHR$(12)) to clear a terminal screen and return the 
cursor to the home position. 
EXAMPLE: 

PRINT CHR$(66) 

B 

Ok 


See the ASC function for ASCll-to-numeric conversion. 


FORMAT: 
CINT(X) 
ACTION: 


Converts X to an integer by rounding the fractional portion. If X is not 
in the range -32768 to 32767, an “Overflow” error occurs. 


EXAMPLE: 


PRINT CINT(45.67) 
46 
Ok 


See the CDBL and CSNG functions for converting numbers to the 


double precision and single precision data type. See also the FIX and 
INT functions, both of which return integers. 


FORMAT: 
COS(X) 
ACTION: 


Returns the cosine of X in radians. The calculation of COS(X) is 
performed in Single precision. 


EXAMPLE: 


10 X = 2*COS(4) 
20 PRINT X 
RUN 

1.842122 
Ok 


3.8 CSNG 


eee 
3.9 CVI, CVS, CVD 


3.10 DATE$ 
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FORMAT: 
CSNG(X) 
ACTION: 
Converts X to a single precision number. 
EXAMPLE: 
10 A* = 975.34217# 
20 PRINT A#; CSNG(A#) 
RUN 
975.34217 975.341 
Ok 


See the CINT and CDBL functions for converting numbers to the 
integer and double precision data types. 


FORMAT: 

CVI(<2-byte string>) 

CVS(<4-byte string>) 

CVD(<8-byte string>) 

ACTION: 

Converts string values to numeric values. Numeric values that are 
read in from a random disk file must be converted from strings back 
into numbers. CVI converts a 2-byte string to an integer. CVS 
converts a 4-byte string to a single precision number. CVD converts 


an 8-byte string to a double precision number. 


EXAMPLE: 


70 FIELD #1,4 AS N$, 
12 AS BS,... 

80 GET #] 

90 Y=CVS(N$) 


See also Appendix B. 


FORMAT: 
DATE$ 


t 


w 


3.11 EOF 


3.12 EXP 


ACTION: 


Sets or retrieves the current date. Returns a ten-character string 
variable with the following format: 


mm-dd-yyyy 


where: mm 
dd 


yyyy 
/ 


month (1-12) 
date (1-31) 
year (1980-99) 
delimiter 
delimiter 


Wo Wom ob 


Leading zeros are presumed for single-digit months and dates. 
Double-digit years are presumed to begin with 19, so that specify- 
ing 99 indicates the year 1999. DATE$ can be used like any string 
variable, although it is constantly being incremented by a hardware 
clock. Note that either of the common delimiters “/” or “-” can be 
used between digits. 


NOTE: DATE$ does not support the European format dd-mm-yy. 
EXAMPLE: 

DATE$ = “10-21-82” 

Ok 

PRINT DATE$ 


10-21-1982 
Ok 


FORMAT: 

EOF(<file number>) 

ACTION: 

Returns -1 (true) if the end of a sequential file has been reached. Use 


EOF to test for end-of-file while INPUTting, to avoid “Input past end” 
errors. 


EXAMPLE: 
10 OPEN “I”,1 “DATA” 
20 C=0 
30 IF EOF(1) THEN 100 
40 INPUT #1,M(C) 
50 C=C+1:GOTO 30 
FORMAT: 
EXP(X) 
ACTION: 
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Returns e to the power of X. X must be <=87.3365. If EXP overflows, 
the “Overflow” error message is displayed, machine infinity with the 
appropriate sign is supplied as the result, and execution continues. 


EXAMPLE: 
10X=5 V 
20 PRINT EXP (X-1) 
RUN 
54.5982 
Ok 
(a eg CT 
3.13 FIX FORMAT: 
FIX(X) 
ACTION: 


Returns the truncated integer part of X. FIX(X) is equivalent to 
SGN(X)*INT(ABS(X)). The major difference between FIX and INT is 
that FIX does not return the next lower number for negative X. 


EXAMPLES: 
PRINT FIX(58.75) 
58 
Ok 
PRINT FIX(-58.75) 
-58 
Ok 
Bi r a eee 
3.14 FRE FORMAT: 
FRE(0) 
FRE(X$) 
ACTION: 


Arguments to FRE are dummy arguments. FRE returns the number of 
bytes in memory not being used by MS-BASIC. 


FRE(“") forces a garbage collection before returning the number of 
free bytes. BE PATIENT: garbage collection may take 1 to 1-1/2 
minutes. MS-BASIC will not initiate garbage collection until all free 
memory has been used up. Therefore, using FRE("”) periodically will 
result in shorter delays for each garbage collection. 


EXAMPLE: 
PRINT FRE(O) 


14542 
Ok 
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3.15 HEX$ 


3.16 INKEY$ 


i) 
3.17 INP 


FORMAT: 
HEX$(X) 
ACTION: 


Returns a string which represents the hexadecimal value of the 
decimal argument. X is rounded to an integer before HEX$(X) is 
evaluated. 


EXAMPLE: 


10 INPUT X 
20 A$ = HEX$(X) 
30 PRINT X “DECIMAL IS ” A$ “ HEXADECIMAL” 
RUN 
? 32 

32 DECIMAL IS 20 HEXADECIMAL 
Ok 


See the OCT$ function for octal conversion. 

FORMAT: 

INKEY$ 

ACTION: 

Returns either a one-character string containing a character read 
from the terminal or a null string if no character is pending at the 
terminal. No characters will be echoed and all characters are passed 
through to the program except for ALT-C, which terminates the 


program. (With the MS-BASIC Compiler, ALT-C is also passed through 
to the program.) 


EXAMPLE: 
1000 ‘TIMED INPUT SUBROUTINE 
1010 RESPONSE$=“” 
1020 FOR I%=1 TO TIMELIMIT% 
1030 A$=INKEY$ : IF LEN(A$)=0 THEN 1060 
1040 IF ASC(A$)=13 THEN TIMEOUT%=0 : RETURN 
1050 RESPONSE$=RESPONSE$+A$ 
1060 NEXT I% 
1070 TIMEOUT%=1 : RETURN 


FORMAT: 

INP(I) 

where | is a valid machine port number in the range 0 to 65535. 
ACTION: 


Returns the byte read from port |. 
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3.18 INPUT$ 


3.19 INSTR 
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REMARKS: 
INP is the complementary function to the OUT statement. 
EXAMPLE: 
100 A=INP (54321) 
In assembly language, this is equivalent to: 


MOV DX,54321 
IN AL,DX 


FORMAT: 
INPUTS$(X[,[#]Y]) 
ACTION: 


Returns a string of X characters, read from the terminal or from file 
number Y. If the terminal is used for input, no characters will be 
echoed and all ALT characters are passed through except ALT-C, 
which is used to interrupt the execution of the INPUT$ function. 


Example: 


5 ‘LIST THE CONTENTS OF A SEQUENTIAL FILE IN 
HEXADECIMAL 

10 OPEN“I”,1 “DATA” 

20 IF EOF(1) THEN 50 

30 PRINT HEX$(ASC(INPUT$(1,#1))); 

40 GOTO 20 

50 PRINT 


60 END 


100 PRINT “TYPE P TO PROCEED OR $S TO STOP” 
110 X$=INPUT$(1) 

120 IF X$=“P” THEN 500 

130 IF X$="S” THEN 700 ELSE 100 


FORMAT: 
INSTR([I,]X$,Y$) 
ACTION: 


Searches for the first occurrence of string Y$ in X$ and returns the 
position at which the match is found. Optional offset | sets the 


3.20 INT 


3.21 LEFT$ 


position for starting the search. | must be in the range 1 to 255. If 
[>LEN(X$) or if X$ is null or if Y$ cannot be found, INSTR 
returns 0. If Y$ is null, INSTR returns | or 1. X$ and Y$ may be 
string variables, string expressions or string literals. 


EXAMPLE: 
10 X$ = “ABCDEB” 
20 Y$ = “B” 
30 PRINT INSTR(X$,Y $); INSTR(4,X$,Y$) 
RUN 
e 6 
Ok 


NOTE: If I=0 is specified, error message ‘Illegal function call in <line 
number>" will be returned. 
FORMAT: 
INT(X) 
ACTION: 
Returns the largest integer <=X. 
Examples: 

PRINT INT(99.89) 

99 
Ok 
PRINT INT(-12.11) 


13 
Ok 


See the FIX and CINT functions which also return integer values. 


FORMAT: 
LEFT$(X$,1) 
ACTION: 
Returns a string comprised of the leftmost | characters of X$. | must 
be in the range 0 to 255. If | is greater than LEN(X$), the entire string 
(X$) will be returned. If 1=0, the null string (length zero) is returned. 
EXAMPLE: 

10 A$ = “BASIC PROGRAM” 

20 B$ = LEFT$(A$5) 

30 PRINT B$ 

BASIC 

Ok 


Also see the MID$ and RIGHTS$ functions. 
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3.22 LEN 


3.23 LOC 


3.24 LOG 


3.25 LPOS 
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FORMAT: 
LEN(X$) 
ACTION: 


Returns the number of characters in X$. Nonprinting characters and 
blanks are counted. 


EXAMPLE: 
10 X$ = “PORTLAND, OREGON” 
20 PRINT LEN(X$) 
16 
Ok 
FORMAT: 


LOC(<file number>) 

ACTION: 

With random disk files, LOC returns the record number just read or 
written from a GET or PUT. If the file was opened but no disk I/O 
has been performed yet, LOC returns a 0. With sequential files, LOC 
returns the number of sectors (128 byte blocks) read from or written 
to the file since it was OPENed. 

EXAMPLE: 


200 IF LOC(1)>80 THEN STOP 
FORMAT: 


LOG(X) 
ACTION: 
Returns the natural logarithm of X. X must be greater than zero. 
EXAMPLE: 

PRINT LOG(45/7) 

1.860752 

Ok 
FORMAT: 
LPOS(X) 
ACTION: 
Returns the current position of the line printer print head within the 


line printer buffer. Does not necessarily give the physical position of 
the print head. X is a dummy argument. 


3.26 MID$ 


a 
3.27 MKI$, MKSS, 


MKD$ 


EXAMPLE: 


100 IF LPOS(X)>60 THEN LPRINT CHR$(13) 
FORMAT: 

MID$(X$,I[,J]) 

ACTION: 


Returns a string of length J characters from X$ beginning with the Ith 
character. | and J must be in the range 1 to 255. If J is omitted or if 
there are fewer than J characters to the right of the Ith character, all 
rightmost characters beginning with the Ith character are returned. If 
| >rLEN(x$), MID$ returns a null string. 


EXAMPLE: 


LIST 

10 A$="GOOD ” 

20 B$=“MORNING EVENING AFTERNOON” 
30 PRINT A$;MID$(B$,9,7) 

Ok 

RUN 

GOOD EVENING 

Ok 


Also see the LEFT$ and RIGHT$ functions. 


NOTE: If l=0 is specified, error message “ILLEGAL FUNCTION CALL 
IN <line number>" will be returned. 


FORMAT: 


MKI$(<integer expression>) 
MKS$(<single-precision expression>) 


MKD$(<double-precision expression>) 
ACTION: 


Convert numeric values to string values. Any numeric value that is 
placed in a random file buffer with an LSET or RSET statement must 
be converted to a string. MKI$ converts an integer to a 2-byte string. 
MKS$ converts a single precision number to a 4-byte string. MKD$ 
converts a double precision number to an 8-byte string. 


EXAMPLE: 


90 AMT=(K+T) 

100 FIELD #1, 8 AS D$, 20 AS N$ 
110 LSET D$ = MKS$( AMT) 

120 LSET N$ = A$ 

130 PUT #1 


See also Appendix B. 
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3.28 OCT$ 


es ener 
3.29 PEEK 


ee a eS Td 
3.30 POS 


(TNC 
3.31 RIGHT$ 
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FORMAT: 
OCT$(X) 
ACTION: 


Returns a string which represents the octal value of the decimal 
argument. X is rounded to an integer before OCT$(X) is evaluated. 


EXAMPLE: 
PRINT OCT$(24) 
30 
Ok 


See the HEX$ function for hexadecimal conversion. 


FORMAT: 

PEEK(!) 

ACTION: 

Returns the byte (decimal integer in the range 0 to 255) read from 
memory location |. | must be in the range O to 65536. PEEK is the 
complementary function to the POKE statement, Section 2.47. 


EXAMPLE: 


A=PEEK(&HS5SA00) 


FORMAT: 
POS(I) 
ACTION: 


Returns the current cursor position. The leftmost position is 1. X is a 
dummy argument. 


EXAMPLE: 
IF POS(X)>60 THEN PRINT CHR$(13) 


Also see the LPOS function. 


FORMAT: 
RIGHTS$(X$,1) 


3.32 RND 


3.33 SGN 


ACTION: 


Returns the rightmost | characters of string X$. If IFLEN(X$), returns 
X$. If I=0, the null string (length zero) is returned. 


EXAMPLE: 
10 A$=“DISK BASIC” 
20 PRINT RIGHT$(A$,8) 
RUN 
BASIC 
Ok 


Also see the MID$ and LEFT$ functions. 


FORMAT: 

RND[(X)] 

ACTION: 

Returns a random number between 0 and 1. The same sequence of 
random numbers is generated each time the program is RUN unless 


the random number generator is reseeded (see RANDOMIZE, Section 
2.52). However, X<0 always restarts the same sequence for any given 
X. 


X>0 or X omitted generates the next random number in the 
sequence. X=0 repeats the last number generated. 
EXAMPLE: 

10 FOR I=1 TO 5 

20 PRINT INTC RND*100); 

50 NEXT I 


Will print 5 random numbers between 0 and 100. 


FORMAT: 
SGN(X) 
ACTION: 


If X>0, SGN(X) returns 1. If X=0, SGN(X) returns 0. If X<0, 
SGN(X) returns -1. 


EXAMPLE: 
ON SGN(X)+2 GOTO 100,200,500 


branches to 100 if X is negative, 200 if X is O and 300 if X is positive. 


81 


3.34 SIN 


3.35 SPACE$ 


3.36 SPC 
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FORMAT: 
SIN(X) 
ACTION: 


Returns the sine of X in radians. SIN(X) is calculated in single 
precision. 


COS(X)=SIN(X+3.14159/2). 
EXAMPLE: 


PRINT SIN(1.5) 
9974951 
Ok 


FORMAT: 
SPACE$(X) 
ACTION: 


Returns a string of spaces of length X. The expression X is rounded 
to an integer and must be in the range 0 to 255. 


EXAMPLE: 


10 FOR I = 1 TO8 
20 X$ = SPACE$(I) 
50 PRINT X$;I 
40 NEXT I 
RUN 

l 

R 

ő 
4 
5 

Ok 


Also see the SPC function. 


FORMAT: 

SPC(I) 

ACTION: 

Prints | blanks on the terminal. SPC may only be used with PRINT 


and LPRINT statements. | must be in the range 0 to 255. A'; is 
assumed to follow the SPC(l) commana. 


er 
3.37 SQR 


3.38 STR$ 


ee oe 
3.39 STRINGS 


EXAMPLE: 
PRINT “OVER” SPC(15) “THERE” 
OVER THERE 
Ok 

Also see the SPACE$ function. 

FORMAT: 

SQR(X) 

ACTION: 


Returns the square root of X. X must be >=0. 


EXAMPLE: 
10 FOR X = 10 TO 25 STEP 5 
20 PRINT X, SQR(X) 
30 NEXT 
RUN 
10 3.162278 
15 5.872984 
20 4.472156 
25 5 
Ok 
FORMAT: 
STR$(X) 
ACTION: 


Returns a string representation of the value of X. 


EXAMPLE: 
5 REM ARITHMETIC FOR KIDS 


10 INPUT “TYPE A NUMBER”;N 
20 ON LEN(STR$(N)) GOSUB 30,100,200,300,400,500 


Also see the VAL function. 
FORMATS: 


STRINGS(I,J) 
STRING$(I,X$) 
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ACTION: 


Returns a string of length | whose characters all have ASCII code J 
or the first character of X$. 


EXAMPLE: 
10 X$ = STRING$( 10,45) 
20 PRINT X$ “MONTHLY REPORT” X$ 
RUN 
--—--—-MONTHLY REPORT--—-———- 
Ok 
eae 
3.40 TAB FORMAT: 
TAB(I) 
ACTION: 
Spaces to position | on the terminal. If the current print position is 
already beyond space |, TAB goes to the same position on the next 
line. 1 is the leftmost position, and the rightmost position is the width 
minus one. | must be in the range 1 to 255. TAB may only be used in 
PRINT and LPRINT statements. 
EXAMPLE: = 
10 PRINT “NAME” TAB(25) “AMOUNT” : PRINT 
20 READ A$,B$ 
50 PRINT A$ TAB(25) B$ 
40 DATA “G. T. JONES” ,”$25.00” 
RUN 
NAME AMOUNT 
G. T. JONES $25.00 
Ok 
ae ey 
3.41 TAN FORMAT: 
TAN(X) 
ACTION: 


Returns the tangent of X in radians. TAN(X) is calculated in single 

precision. If TAN overflows, the “Overflow” error message is 

displayed, machine infinity with the appropriate sign is supplied as the a 
result, and execution continues. 


EXAMPLE: 


10 Y = Q*TAN(X)/2 
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3.42 TIMES 


3.43 USR 


3.44 VAL 


FORMAT: 
TIMES 
ACTION: 


Sets or retrieves the current time. Returns an eight-character string 
variable with the following format: 


hh:mm:ss 

where: hh = hour of day (0-23) 
mm = minutes (0-59) 
ss = seconds (0-59) 


delimiter 


Minutes and seconds are optional, and the time defaults to 
“00:00:00”. Leading zeros are optional. TIME$ can be used like any 
string variable, although it is being incremented constantly by a 
hardware clock. 


EXAMPLE: 
TIME$ = “08:00” 
Ok 
PRINT TIME$ 
08:00:04 
Ok 

Format: 

USR[<digit>](X) 

ACTION: 


Calls the user's assembly language subroutine with the argument X. 
<digit> is in the range 0 to 9 and corresponds to the digit supplied 
with the DEF USR statement for that routine. If <digit> is omitted, 
USRO is assumed. See Appendix E. 


EXAMPLE: 
40 B = T*SIN(Y) 
50 C = USR(B/&8) 
60 D = USR(B/3) 

FORMAT: 

VAL(X$) 


Returns the numerical value of string X$. The VAL function also strips 
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3.45 VARPTR 
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leading blanks, tabs, and linefeeds from the argument string. For 
example: 


VAL(“ -3) 
returns -3. 
EXAMPLE: 


10 READ NAME$,CITY$ STATE$ ZIP$ 

20 IF VAL(ZIP$)<90000 OR VAL(ZIP$)>96699 THEN 
PRINT NAME$ TAB(25) “OUT OF STATE” 

30 IF VAL(ZIP$)>=90801 AND VAL( ZIP$)<=90815 
THEN 

PRINT NAME$ TAB(25) “LONG BEACH” 


See the STR$ function for numeric to string conversion. 


FORMAT 1: 
VARPTR(<varlable name>) 
FORMAT 2: 

VARPTR(#<file number>) 
ACTION: 


Format 1: Returns the address of the first byte of data identified with 
<variable name>. A value must be assigned to <variable name> 
prior to execution of VARPTR. Otherwise an "Illegal function call” 
error results. Any type variable name may be used (numeric, string, 
array), and the address returned will be an integer in the range 32767 
to -32768. If a negative address is returned, add it to 65536 to obtain 
the actual address. 


VARPTR is usually used to obtain the address of a variable or array 
so it may be passed to an assembly language subroutine. A function 
call of the form VARPTR(A(Q)) is usually specified when passing an 

array, so that the lowest-addressed element of the array is returned. 


NOTE: All simple variables should be assigned before calling VARPTR 
for an array, because the addresses of the arrays change whenever a 
new simple variable is assigned. 

Format 2: For sequential files, returns the starting address of the disk 
I/O buffer assigned to <file number>. For random files, returns the 
address of the FIELD buffer assigned to <file number>. 


EXAMPLE: 


100 X=USR( VARPTR(Y)) 


a 
A.1 STRING 
DIMENSIONS 


ne ee 
A.2 MULTIPLE 
ASSIGNMENTS 


APPENDIX A: Converting Programs to MS-BASIC 


lf you have programs written in a BASIC other than MS-BASIC, some 
minor adjustments may be necessary before running them. Here are 
some specific things to look for when converting BASIC programs. 


Delete all statements that are used to declare the length of strings. A 
statement such as DIM A§$(I,J), which dimensions a string array for J 
elements of length |, should be converted to the MS-BASIC statement 
DIM A$(J). 


Some BASICs use a comma or ampersand for string concatenation. 
Each of these must be changed to a plus sign, which is the operator 
for MS-BASIC string concatenation. 


In MS-BASIC, the MID$, RIGHT$, and LEFT$ functions are used to 
take substrings of strings. Forms such as A$(I) to access the Ith 
character in A$, or A$(I,J) to take a substring of A$ from position | to 
position J, must be changed as follows: 


OTHER BASIC MS-BASIC 
X$=AG(I) X$=MID$(A$,,1) 
X$=A$(I,J) X$=MID$(A$,1,J-I+1 ) 


If the substring reference is on the left side of an assignment and X$ 
is used to replace characters in A$, convert as follows: 


OTHER BASIC MS-BASIC 
A$(1)=X$ MID$(A$,1,1)=X$ 
AS$(1,J9)=X$ MID$(A$,I,J-1+1 )=X$ 


Some BASICs allow statements of the form: 


10 LET B=C=0 


to set B and C equal to zero. MS-BASIC would interpret the second 
equal sign as a logical operator and set B equal to -1 if C equaled 0. 
Instead, convert this statement to two assignment statements: 


10 C=0:B=0 
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A.3 MULTIPLE 
STATEMENTS 


ee 
A.4 MAT FUNCTIONS 


Some BASICs use a backslash \ to separate multiple statements on 
a line. With MS-BASIC, be sure all statements on a line are separated 
by a colon (:). 


Programs using the MAT functions available in some BASICs must be 
rewritten using FOR ... NEXT loops to execute properly. 


Fe ee ae] 
B.1 PROGRAM FILE 


COMMANDS 


APPENDIX B: MS-BASIC Disk 1/O 


Disk I/O procedures for the beginning MS-BASIC user are examined 
in this appendix. If you are new to MS-BASIC or if you're getting disk- 
related errors, read through these procedures and program examples 
to make sure you're using all the disk statements correctly. 


Wherever a filename is required in a disk command or statement, use 
a name that conforms to your operating system's requirements for 
filenames. (See Appendix C for CP/M-86 and Appendix D for 


MS-DOS.) 


Here is a review of the commands and statements used in program 


file manipulation. 


SAVE <fllename>[,A] 


LOAD <filename>{,R] 


RUN <filename>[,R] 


MERGE <filename> 


Writes to disk the program currently 
residing in memory. Optional A writes the 
program as a series of ASCII characters. 
(Otherwise, MS-BASIC uses a 
compressed binary format.) 


Loads the program from disk into 
memory. Optional R runs the program 
immediately. LOAD always deletes the 
current contents of memory and closes 
all files before LOADing. If R is included, 
however, open data files are kept open. 
Thus programs can be chained or 
loaded in sections and access the same 
data files. (LOAD <filename>,R and RUN 
<filename>.R are equivalent.) 


RUN <filename> loads the program from 
disk into memory and runs it. RUN 
deletes the current contents of memory 
and closes all files before loading the 
program. If the R option is included, 
however, all open data files are kept 
open. (RUN <filename>,R and LOAD 
<filename>,R are equivalent.) 


Loads the program from disk into 
memory but does not delete the current 
contents of memory. The program line 
numbers on disk are merged with the 
line numbers in memory. If two lines 
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have the same number, only the line 
from the disk program is saved. After a 
MERGE command, the “merged” 
program resides in memory, and 
MS-BASIC returns to command level. 


KILL <filename> Deletes the file from the disk. 
<filename> may be a program file, or a 
sequential or random access data file. 


NAME <old filename> To change the name of a disk file, 

AS<new filename> execute the NAME statement, NAME 
<oldfile> AS <newfile>. NAME may be 
used with program files, random files, or 
sequential files. 


If you wish to save a program in an encoded binary format, use the 
“Protect” option with the SAVE command. For example: 


SAVE “MYPROG" P 


A program saved this way cannot be listed or edited. You may also 
want to save an unprotected copy of the program for listing and 
editing purposes. 


There are two types of disk data files that may be created and 
accessed by a MS-BASIC program: sequential files and random 
access files. 


Sequential files are easier to create than random files but are limited 
in flexibility and speed when it comes time to access the data. Data 
that is written to a sequential file is a series of ASCII characters 
Stored, one item after another (sequentially), in the order it is sent and 
is read back in the same way. 


The statements and functions that are used with sequential files are: 


OPEN PRINT# INPUT# WRITE# 
PRINT# USING LINE INPUT# 


CLOSE EOF LOC 


The following program steps are required to create a sequential file 
and access the data in the file: 


1. OPEN the file in “O” mode. OPEN “O”,#1,“DATA” 


2. Write data to the file PRINT#1 ,A$;B$;C$ 
using the PRINT# statement. 
(WRITE# may be used instead.) 


3. To access the data in the CLOSE #1 
file, you must CLOSE the file OPEN “T”,#1,“DATA” 
and reOPEN it in “I” mode. 


4. Use the INPUT# statement to INPUT#1 X$,Y$,Z$ 
read data from the sequential file into 
the program. 


Figure B-1 is a short program that creates a sequential file, “DATA”, 
from information you input at the terminal. 


Figure B-1: Creating a Sequential Data File 


10 OPEN “O”,#1,“DATA” 

20 INPUT “NAME”; N$ 

25 IF N$=“DONE” THEN END 
30 INPUT “DEPARTMENT”;D$ 
40 INPUT “DATE HIRED”;H$ 
50 PRINT#1,N$;“,";D$;“,";H$ 
60 PRINT:GOTO 80 

RUN 

NAME? MICKEY MOUSE 
DEPARTMENT? AUDIO/VISUAL AIDS 
DATE HIRED? 01/12/72 


NAME? SHERLOCK HOLMES 
DEPARTMENT? RESEARCH 
DATE HIRED? 12/03/65 


NAME? EBENEEZER SCROOGE 
DEPARTMENT? ACCOUNTING 
DATE HIRED? 04/27/78 


NAME? SUPER MANN 
DEPARTMENT? MAINTENANCE 
DATE HIRED? 08/16/78 


NAME? etc. 


oe _ | e 


Now look at Figure B-2. It accesses the file “DATA” that was created 
in Program 1 and displays the name of everyone hired in 1978. 


Figure B-2: Accessing a Sequential File 


10 OPEN “I” ,#1,“DATA” 

20 INPUT#1,N$,D$,H$ 

30 IF RIGHT$(H$,2)="78" THEN PRINT N$ 
40 GOTO 20 

RUN 

EBENEEZER SCROOGE 

SUPER MANN 

Input past end in 20 

Ok 


The program in Figure B-2 reads, sequentially, every item in the file. 
When all the data has been read, line 20 causes an “Input past end” 
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error. To avoid getting this error, insert line 15 which uses the EOF 
function to test for end-of-file: 


15 IF EOF(1) THEN END 


and change line 40 to GOTO 15. 


A program that creates a sequential file can also write formatted data 
to the disk with the PRINT# USING statement. For example, the 
Statement: 


PRINT#1 USING #### ##,”-A BCD 


could be used to write numeric data to disk without explicit delimiters. 
The comma at the end of the format string serves to separate the 
items in the disk file. 


The LOC function, when used with a sequential file, returns the 
number of sectors that have been written to or read from the file 
since it was OPENed. A sector is a 128-byte block of data. 


lf you have a sequential file residing on disk and later want to add 
more data to the end of it, you cannot simply open the file in “O” 
mode and start writing data. As soon as you open a sequential file in 
“O” mode, you destroy its current contents. The following procedure 
can be used to add data to an existing file called “NAMES”. 


1. OPEN “NAMES” in “I” mode. 

2. OPEN a second file called “COPY” in “O” mode. 

3. Read in the data in "NAMES" and write it to “COPY”. 
4. CLOSE “NAMES” and KILL it. 

5. Write the new information to “COPY”. 

6. Rename "COPY" as “NAMES” and CLOSE. 


7. Now there is a file on disk called “NAMES” that includes all the 
previous data plus the new data you just added. 


Figure B-3 illustrates this technique. It can be used to create or add 
onto a file called NAMES. This program also illustrates the use of 
LINE INPUT# to read strings with embedded commas from the disk 
file. Remember, LINE INPUT# will read in characters from the disk 
until it sees a carriage return (it does not stop at quotes or commas) 
or until it has read 255 characters. 


Figure B-3: Adding Data to a Sequential File 


10 ON ERROR GOTO 2000 

20 OPEN "I”,#1 "NAMES" 

30 REM IF FILE EXISTS, WRITE IT TO “COPY” 
40 OPEN “O”,#2,“COPY” 


